feat: drift-check §11 CI-Workflows 大版本指针完整性检测（红队 #6-A，ADR-0016） by randypanding · Pull Request #49 · Cloudbird-Software/.github

randypanding · 2026-08-19T03:39:35Z

ADR-0016（决策 3 检测侧；文档侧配套 PR 在 CI-Workflows 仓）

问题（CI-Workflows #6-A，复核属实）：全部业务仓 gate 引用 CI-Workflows@v1 浮动指针；release-tags ruleset 禁 update/deletion 但 bypass_actors 含 OrganizationAdmin(always)——admin 强移 v1 即改变所有业务仓实际执行的 CI，且此前无任何检测会发现（红队线上实测 v1→8cccf1b 与 v1.2.0 相同，纯靠自觉）。

修复：drift-check 新增 §11（每日 03:00 UTC 随 governance-drift 运行）：

校验不变式：每个大版本指针 tag vN == 最高 vN.x.y 指向的 commit（v2+ 出现时自动适用）
附注 tag（annotated）指向 tag 对象而非 commit——解引用到 commit 再比对，避免两个指向同一 commit 的附注 tag 误报
指针存在但无 vN.x.y 锚点 / 解引用失败 / 列表拉取失败均 fail-closed 计漂移
admin 强移指针 ⇒ 最长 24h 内漂移报警——不可见通道变可检测

为何不移除 admin bypass：org admin 是灾备最后恢复手段（SECURITY.md 破玻璃语义）；正确姿势=保留恢复能力+滥用可检测。

本地实测（真实 org 数据）：OK CI-Workflows 指针 'v1' == v1.2.0（8cccf1b）；bash -n 通过。存量 2 项 §8 直推漂移与本变更无关（历史事实，每日工作流已在报）。

全部业务仓 gate 引用 CI-Workflows@v1 浮动指针，release-tags ruleset 的 admin bypass 使指针可被强移且此前无任何检测。§11 每日校验不变式 vN==最高 vN.x.y 的 commit（附注 tag 解引用后比对）——强移 24h 内检出。

coderabbitai · 2026-08-19T03:39:47Z

Warning

Review limit reached

@randypanding, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 24 minutes

Limit details: You’ve used all 3 included reviews currently available.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 32972941-25b5-4583-bef2-098a0c97c3dd

📥 Commits

Reviewing files that changed from the base of the PR and between 0ffe714 and 8e85836.

📒 Files selected for processing (1)

governance/drift-check.sh

_{Comment @coderabbitai help to get the list of available commands.}

qodo-code-review · 2026-08-19T03:40:55Z

PR Summary by Qodo

Detect CI-Workflows major-version tag drift

✨ Enhancement 🕐 10-20 Minutes

AI Description

• Validates each CI-Workflows vN pointer against its highest vN.x.y release.
• Dereferences annotated tags before comparing commits to prevent false drift reports.
• Fails closed on missing anchors, API errors, and dereference failures.

Diagram

sequenceDiagram
  actor Scheduler as Daily Scheduler
  participant Workflow as Drift Workflow
  participant Script as Pointer Check
  participant Refs as Refs API
  participant Tags as Tags API
  participant Issue as Drift Reporter
  Scheduler->>Workflow: Run at 03:00 UTC
  Workflow->>Script: Execute section 11
  Script->>Refs: List repository tags
  Refs-->>Script: Pointers and releases
  opt Annotated tag
    Script->>Tags: Resolve tag object
    Tags-->>Script: Return commit SHA
  end
  alt Pointer matches release
    Script-->>Workflow: Report OK
  else Missing or mismatched
    Script-->>Workflow: Return drift
    Workflow->>Issue: Create or update issue
  end

High-Level Assessment

The following are alternative approaches to this PR:

1. Remove administrator bypass

➕ Prevents administrators from force-moving protected release tags during normal operation.
➕ Changes protection from post-hoc detection to preventive enforcement.
➖ Removes the documented break-glass recovery capability.
➖ Could block emergency restoration when normal governance controls are unavailable.

2. Pin consumers to immutable SHAs

➕ Eliminates trust in mutable major-version pointers.
➕ Makes each repository's executed workflow revision explicit and auditable.
➖ Requires coordinated updates across every consuming repository for each release.
➖ Sacrifices the automatic compatibility updates intended by major-version tags.

3. Event-driven tag monitoring

➕ Can detect pointer movement immediately instead of within the daily window.
➕ Provides a direct audit signal for each tag mutation.
➖ Requires additional webhook or GitHub App infrastructure and credentials.
➖ Adds operational complexity beyond the existing governance-drift workflow.

Recommendation: Keep the PR's daily invariant check: it preserves the documented administrator break-glass path while making misuse detectable through the existing drift-reporting mechanism. Removing bypass is operationally risky, and immutable consumer pins impose substantial rollout overhead; event-driven monitoring could be added later if the maximum 24-hour detection window becomes unacceptable.

Files changed (1) +46 / -0

Enhancement (1) +46 / -0

drift-check.shAdd CI-Workflows major-tag integrity validation +46/-0

Add CI-Workflows major-tag integrity validation

• Adds drift-check section 11 to compare every 'vN' pointer with the highest matching 'vN.x.y' release by resolved commit SHA. It handles lightweight and annotated tags, automatically covers future major versions, and records drift when tag retrieval, anchoring, dereferencing, or equality validation fails.

governance/drift-check.sh

qodo-code-review · 2026-08-19T03:43:52Z

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. ~~Tag 分页导致假绿~~ ✓ Resolved 🐞 Bug ≡ Correctness

Description

matching-refs 请求只读取第一页，后续页中的大版本指针或更高 vN.x.y tag 不会进入 HIGHEST 计算。tag 数量超过单页限制后，脚本可能拿旧版本比较并错误输出
OK。

Code

governance/drift-check.sh[307]

+CW_REFS=$(api "https://api.github.com/repos/$ORG/CI-Workflows/git/matching-refs/tags/")

Relevance

●●● Strong
PR #19 explicitly accepted pagination fixes for drift-check API queries causing missed objects and
false green results.
PR-#19

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
新增请求没有 per_page、page 或 Link 分页处理，后续的指针查找和最高版本计算完全依赖这一份响应。GitHub 文档说明结果较多的 REST 响应会分页；同文件已有 API
清单显式逐页拉取，也证明 api() 本身不会自动分页。
governance/drift-check.sh[19-20]
governance/drift-check.sh[307-330]
🌐 GitHub REST API 在结果较多时使用分页，调用方必须遍历页面以取得完整结果。
PR-#19

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
§11 只读取 GitHub matching-refs API 的第一页，因此可能遗漏大版本指针或最高具体版本，并产生供应链完整性假绿。

## Issue Context
应逐页请求并验证每页均为数组，将全部 refs 聚合后再生成 `CW_NAMES`。任何页面请求或解析失败都必须记录漂移，且不能使用部分结果继续比较。

## Fix Focus Areas
- governance/drift-check.sh[307-330]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

2. ~~缺失 v1 被判正常~~ ✓ Resolved 🐞 Bug ☼ Reliability

Description

所有业务仓依赖的 v1 被删除时，循环不会检查它，且没有其他大版本指针时第 345 行会明确输出 OK。管理员因 bypass 删除该供应链入口后，§11 因此无法报告指针缺失。

Code

governance/drift-check.sh[R344-345]

+  done < <(grep -E '^v[0-9]+$' <<<"$CW_NAMES" | sort -V)
+  [[ $PTR_FOUND -eq 0 ]] && ok "CI-Workflows 无大版本指针 tag（不变式不适用）"

Relevance

●●● Strong
The finding exposes a deterministic fail-open gap contradicting this PR’s explicit v1 invariant and
team’s recent drift-hardening pattern.
PR-#19

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

新增注释确认所有业务仓使用 CI-Workflows@v1；但实现只枚举响应中已经存在的 vN，并在枚举结果为空时报告不变式不适用，未建立必需 v1 的存在性断言。

governance/drift-check.sh[302-306]
governance/drift-check.sh[324-345]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
当前逻辑只校验已经存在的大版本 tag，并把零指针状态判为正常，因此删除业务仓依赖的 `v1` 不会产生漂移。

## Issue Context
从治理配置或明确的必需版本集合中取得至少 `v1`，分别校验其存在性、锚点存在性和 commit 一致性。未来自动发现的 v2+ 指针仍可在此基础上追加检查，但不能用“没有指针”跳过已知依赖。

## Fix Focus Areas
- governance/drift-check.sh[324-345]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

3. CW_REFS uses admin token ✗ Dismissed 📘 Rule violation ⛨ Security

Description

The new CW_REFS API request inherits GH_TOKEN from secrets.GOVERNANCE_TOKEN instead of
obtaining a cloudbrid-agent token through scripts/gh-app-token.sh. The credential is described as
an organization-admin token and is not restricted to the CI-Workflows repository.

Code

governance/drift-check.sh[307]

+CW_REFS=$(api "https://api.github.com/repos/$ORG/CI-Workflows/git/matching-refs/tags/")

Relevance

●●● Strong
Recent PR #19 accepted tightening GitHub App credentials to single-repository cloudbrid-agent
tokens.
PR-#19

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
Rule 2778539 requires GitHub API automation to obtain cloudbrid-agent credentials through
scripts/gh-app-token.sh with single-repository scope. The added request uses the existing api()
helper, which reads an organization-admin GH_TOKEN; the workflow populates that variable directly
from secrets.GOVERNANCE_TOKEN.
Rule 2778539: Agent operations must use the cloudbrid-agent GitHub App identity via scripts/gh-app-token.sh with single-repo tokens
governance/drift-check.sh[307-307]
governance/drift-check.sh[7-22]
.github/workflows/governance-drift.yml[20-28]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new CI-Workflows tag lookup uses the organization-admin `GH_TOKEN`, contrary to the required cloudbrid-agent GitHub App identity and single-repository token scope.

## Issue Context
Mint a token scoped specifically to `CI-Workflows` through `scripts/gh-app-token.sh`, pass it separately to the drift checker, and use it for the section 11 repository API calls without expanding its use to organization-level checks.

## Fix Focus Areas
- .github/workflows/governance-drift.yml[20-28]
- governance/drift-check.sh[307-319]
- scripts/gh-app-token.sh[20-29]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Context sources

✅ Compliance rules (platform): 7 rules

✅ Web pages:

🌐 refs

🌐 Git references - GitHub Enterprise Server 3.1 Docs

🌐 refs?apiVersion=2026-03-10

+7 more

Review mode: ⚖️ Balanced: This is a security-sensitive supply-chain integrity check that changes runtime CI behavior and involves API/tag dereferencing and fail-closed shell logic; it is localized but warrants a complete careful review.

Tip of the day

💡 Did you know, you can show, collapse, or hide each part of a finding: code, evidence, and all

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

@v1

回应 qodo 意见（2 条 High 落码，1 条 Medium 凭据项以设计依据回复）： 1. Tag 分页假绿（High）：matching-refs 此前只读第一页，tag 超过单页后 HIGHEST 计算基于残缺集合。改为 per_page=100 逐页聚合，每页验证为数组，任一页失败 fail-closed 拒用部分结果；>50 页（5000+ tag）视为异常同样 fail-closed。 2. 缺失 v1 判正常（High）：删除 v1 后旧逻辑输出"无大版本指针（不变式不适用）"=假绿。v1 是全部业务仓 gate 的供应链入口（REPOS.yaml： "业务仓引用 @v1"），指针缺失必须报漂移。新增 CW_REQUIRED_POINTERS 存在性检查；v2+ 出现后仍由既有循环自动纳入锚点/一致性校验。 3. 凭据项（Medium，不落码）：§11 与 §1-§10 共用 GOVERNANCE_TOKEN 是 AGENTS.md 声明的 drift-check 接口（"GH_TOKEN=<org admin> bash governance/drift-check.sh"）；组织级检测本就需要 org 权限，本节只读公开仓 refs，复用不扩大暴露面；工作流仅 schedule/dispatch 于可信 main 运行。已在代码注释中固化该威胁模型说明。验证：对真实 API 全量跑通——"指针 'v1' == v1.2.0（8cccf1b）"+"必需大版本指针存在（v1）"双双 OK；bash -n 通过。

qodo-code-review Bot reviewed Aug 19, 2026

View reviewed changes

Comment thread governance/drift-check.sh Outdated

Comment thread governance/drift-check.sh Outdated

Comment thread governance/drift-check.sh Outdated

randypanding and others added 2 commits August 19, 2026 11:54

Merge branch 'main' into drift-check-v1-pointer

6c163c0

randypanding merged commit bf806e3 into main Aug 19, 2026
6 checks passed

randypanding deleted the drift-check-v1-pointer branch August 19, 2026 04:15

randypanding mentioned this pull request Aug 21, 2026

[自动合并 P2-2] 抑制标记预算门 #87

Closed

Navigation Menu

Uh oh!

feat: drift-check §11 CI-Workflows 大版本指针完整性检测（红队 #6-A，ADR-0016） - #49

feat: drift-check §11 CI-Workflows 大版本指针完整性检测（红队 #6-A，ADR-0016）#49
randypanding merged 3 commits into
mainfrom
drift-check-v1-pointer

randypanding commented Aug 19, 2026

Uh oh!

coderabbitai Bot commented Aug 19, 2026 •

edited

Loading

Review limit reached

Uh oh!

qodo-code-review Bot commented Aug 19, 2026

Uh oh!

qodo-code-review Bot commented Aug 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

randypanding commented Aug 19, 2026

Uh oh!

coderabbitai Bot commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Uh oh!

qodo-code-review Bot commented Aug 19, 2026

PR Summary by Qodo

Uh oh!

qodo-code-review Bot commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

coderabbitai Bot commented Aug 19, 2026 •

edited

Loading

qodo-code-review Bot commented Aug 19, 2026 •

edited

Loading